package com.kexio.enterprise.integration.notification;

import com.kexio.enterprise.integration.notification.domain.Notification;
import com.kexio.enterprise.integration.notification.domain.UserNotification;
import com.kexio.enterprise.integration.notification.preferences.NotificationPreferences;
import com.kexio.enterprise.integration.notification.query.NotificationSearchCriteria;
import com.kexio.enterprise.integration.notification.result.NotificationResult;
import com.kexio.enterprise.integration.notification.schedule.NotificationScheduleResult;
import com.kexio.enterprise.integration.notification.statistics.NotificationStatistics;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 通知服务接口
 * 
 * 提供统一的通知推送功能，支持多种通知渠道和策略
 * 
 * @author Kexio
 * @since 1.0.0
 */
public interface NotificationService {

    /**
     * 发送通知
     * 
     * @param notification 通知内容
     * @return 发送结果
     */
    NotificationResult sendNotification(Notification notification);

    /**
     * 批量发送通知
     * 
     * @param notifications 通知列表
     * @return 发送结果列表
     */
    List<NotificationResult> batchSendNotifications(List<Notification> notifications);

    /**
     * 异步发送通知
     * 
     * @param notification 通知内容
     */
    void sendNotificationAsync(Notification notification);

    /**
     * 发送广播通知
     * 
     * @param notification 通知内容
     * @param userGroup    用户组
     * @return 发送结果
     */
    NotificationResult broadcastNotification(Notification notification, String userGroup);

    /**
     * 发送个性化通知
     * 
     * @param templateId   模板ID
     * @param userId       用户ID
     * @param variables    变量映射
     * @return 发送结果
     */
    NotificationResult sendPersonalizedNotification(String templateId, Long userId, Map<String, Object> variables);

    /**
     * 预定时发送通知
     * 
     * @param notification 通知内容
     * @param sendTime     发送时间
     * @return 调度结果
     */
    NotificationScheduleResult scheduleNotification(Notification notification, LocalDateTime sendTime);

    /**
     * 取消预定时通知
     * 
     * @param scheduleId 调度ID
     * @return 是否成功
     */
    boolean cancelScheduledNotification(String scheduleId);

    /**
     * 标记通知为已读
     * 
     * @param notificationId 通知ID
     * @param userId         用户ID
     * @return 是否成功
     */
    boolean markAsRead(String notificationId, Long userId);

    /**
     * 批量标记通知为已读
     * 
     * @param notificationIds 通知ID列表
     * @param userId          用户ID
     * @return 成功标记的数量
     */
    int batchMarkAsRead(List<String> notificationIds, Long userId);

    /**
     * 删除通知
     * 
     * @param notificationId 通知ID
     * @param userId         用户ID
     * @return 是否成功
     */
    boolean deleteNotification(String notificationId, Long userId);

    /**
     * 批量删除通知
     * 
     * @param notificationIds 通知ID列表
     * @param userId          用户ID
     * @return 成功删除的数量
     */
    int batchDeleteNotifications(List<String> notificationIds, Long userId);

    /**
     * 获取用户通知列表
     * 
     * @param userId   用户ID
     * @param criteria 搜索条件
     * @return 通知列表
     */
    List<UserNotification> getUserNotifications(Long userId, NotificationSearchCriteria criteria);

    /**
     * 获取用户未读通知数量
     * 
     * @param userId 用户ID
     * @return 未读数量
     */
    long getUnreadCount(Long userId);

    /**
     * 获取用户通知统计
     * 
     * @param userId    用户ID
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 统计信息
     */
    NotificationStatistics getUserNotificationStatistics(Long userId, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取系统通知统计
     * 
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 统计信息
     */
    NotificationStatistics getSystemNotificationStatistics(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 设置用户通知偏好
     * 
     * @param preferences 偏好设置
     */
    void setUserPreferences(NotificationPreferences preferences);

    /**
     * 获取用户通知偏好
     * 
     * @param userId 用户ID
     * @return 偏好设置
     */
    NotificationPreferences getUserPreferences(Long userId);

    /**
     * 清理过期通知
     * 
     * @param beforeTime 清理此时间之前的通知
     * @return 清理的数量
     */
    int cleanupExpiredNotifications(LocalDateTime beforeTime);

    /**
     * 重发失败的通知
     * 
     * @param notificationId 通知ID
     * @return 重发结果
     */
    NotificationResult resendNotification(String notificationId);

    /**
     * 批量重发失败的通知
     * 
     * @param notificationIds 通知ID列表
     * @return 重发结果列表
     */
    List<NotificationResult> batchResendNotifications(List<String> notificationIds);
}
